This document provides background on the RHQ storage node installer along with instructions for usage. A storage node refers to a managed instance of Cassandra. The installer is packaged with the main RHQ distribution. Similar to the installer for the RHQ server, this one also runs as a JBoss module.
Throughout this document the terms storage node and Cassandra are used interchangeably. When referring to Cassandra-specific features, configuration files, etc., the term Cassandra is used for clarity.
You currently have to build RHQ from source to get access to the installer. Specifically, you need to build the [feature/cassandra-backend|] branch. The installer can then be accessed from <RHQ_ROOT>/modules/enterprise/server/appserver/target/rhq-server-4.7.0-SNAPSHOT.zip
Unzip the RHQ Server in some directory (to be referenced as <rhq-install-dir>).
Edit <rhq-install-dir>/bin/rhq-server.properties. Set the database properties described in Startup Properties.
Run <rhq-install-dir>/bin/rhq-storage-installer.sh (A corresponding Windows batch file has not yet been implemented).
The installer supports a number of options. Run it with -h or --help to see a list of all the options and how they are used. The installer aims to be easy to use by providing a default value for each option. The installer performs the following steps in the order listed,
Lays down the storage node in <rhq-install-dir>/storage.
Update Cassandra configuration files. At present a few files are modified.
<rhq-install-dir>/storage/conf/cassandra.yaml
<rhq-install-dir>/storage/conf/cassandra-env.sh
<rhq-install-dir>/storage/conf/log4j-server.properties
<rhq-install-dir>/storage/conf/passwd.properties
<rhq-install-dir>/storage/conf/access.properties
Update <rhq-install-dir>/rhq-server.properties
Start Cassandra
Verify that Cassandra is up and ready to accept client requests
By default the storage node is configured to store data files under /var/lib/rhq/storage. The installer will fail and exit if the user who runs the storage node does not have write permissions to /var/lib or if the values specified by the --commit-log, --data, and --saved-caches options point to files and not directories. On Windows the data file default is HOMEDRIVE:\rhq\storage.
Note: --saved-cashes, --data or --commit-log must not be the same as any other data file directory.
Towards the end of the rhq-server.properties files, you will find the rhq.cassandra.seeds property with a lengthy comment that reads,
# A comma-delimited list of seed nodes. Each Cassandra node uses this list as # contact points to find other nodes in the cluster and learn the ring # topology. The RHQ server(s) use this list to connect to the cluster; # therefore, this property MUST BE SET in order for RHQ to talk to Cassandra. # Each entry in the list consists of three fields that are pipe-delimited. The # of an entry is as follows, # # hostname|jmxPort|nativeTransportPort| # rhq.cassandra.seeds=
The seed list is used both by RHQ and by Cassandra. Work is being done so that as nodes are added or removed from the cluster this list will automatically be updated and changes applied to all nodes.
When you install additional nodes, you temporarily need to follow steps for updating seed lists on each node.
Let's say that you install 3 nodes on hosts host1, host2, and host3. On each host machine you need to perform the following steps (assuming installer default options used).
Update rhq-server.properties so that rhq.cassandra.seeds has a value of host1|9160|9042,host2|9160|9042,host3|9160|9042.
Update cassandra.yaml and set the seeds property to "host1,host2,host3".
If the nodes are running, restart them for changes to take effect.
The installer writes log statements to two locations.
stdout
<rhq-install-dir>/logs/rhq-storage-installer.log
You can define the environment variable RHQ_STORAGE_DEBUG to enable debug logging by the installer.
The storage node installer does not apply any changes. Schema changes are handled entirely by the RHQ server installer.